There are various applications that can be used to define vehicular demand for SUMO from existing input data. Traffic demand can also be created and edited visually with netedit. All these applications eventually create XML definitions.

Of course it is also possible to define the demand file manually or to edit generated files with a text editor. Before starting, it is important to know that a vehicle in SUMO consists of three parts:

Both routes and vehicle types can be shared by several vehicles. It is not mandatory to define a vehicle type. If not given, a default type is used. The driver of a vehicle does not have to be modelled explicitly. For the simulation of persons which walk around or ride in vehicles, additional definitions are necessary.

Initially, we will define a vehicle with a route that belongs to it:

By giving such a route definition to sumo (or sumo-gui), sumo will build a red (color=1,0,0) vehicle of type "type1" named "0" which starts at time 0. The vehicle will drive along the streets "beg", "middle", "end", and as soon as it has approached the edge "rend" it will be removed from the simulation.

This vehicle has its own internal route which is not shared with other vehicles. It is also possible to define two vehicles using the same route. In this case the route must be "externalized" - defined before being referenced by the vehicles. Also, the route must be named by giving it an id. The vehicles using the route refer it using the "route"-attribute. The complete change looks like this:

A vehicle may be defined using the following attributes:

Note: when via is not set, any -elements that belong to this route will automatically be used as intermediate edges. Otherwise via takes precedence.

Caution

Any vehicle types or routes referenced by the attributes type or route must be defined before they are used. Loading order is described here.

It is possible to define repeated vehicle emissions ("flows"), which have the same parameters as the vehicle or trip definitions except for the departure time. The id of the created vehicles is "flowId.runningNumber" and they are distributed either equally or randomly in the given interval. The following additional parameters are known:

Flow can define their route explicitly (like vehicles) or with from,to,via (like trips):

One may notice, that the route itself also got a color definition, so the attributes of a route are:

There are a few important things to consider when building your own routes:

Besides values which describe the vehicle's car-following properties, one can find definitions of the assigned vehicles' shapes, emissions, and assignment to abstract vehicle classes. These concepts will be described in the following. Also, you may find further descriptions of implemented car-following models in the subsection #Car-Following Models.

The desired driving speed usually varies among the vehicle of a fleet. In SUMO this is modeled by assigning to each vehicle an individual multiplier which gets applied to the road speed limit. This multiplier is called the individual speedFactor or in short the speedFactor of a vehicle. The product of road speed limit and the individual speed factor gives the desired free flow driving speed of a vehicle. If the individual speedFactor is larger than 1, vehicles can exceed edge speeds. However, vehicle speeds are still capped at the vehicle type's maxSpeed.

While it is possible to assign the individual speedFactor value directly in a , or even definition using attribute speedFactor, a more common use case is to define the distribution of these factors for a .

Having a distribution of speed factors (and hence of desired speeds) is beneficial to the realism of a simulation. If the desired speed is constant among a fleet of vehicles, this implies that gaps between vehicles will keep their size constant over a long time. For this reason, the individual speed factor for each simulated vehicle (whether defined as , or part of a ) is drawn from a distribution by default.

The speedFactor of a vehicle is also multiplied with the value of maxDesiredSpeed of it's vType. The resulting value gives another upper bound on speed. This achieves speed distribution for road users where the speed limit is not meaningful (i.e. bicyles and pedestrians).

The speedFactor of a vehicle is written to various outputs (tripinfo-output, vehroute-output) and can also be checked via the vehicle parameter dialog.

Two types of distributions can be defined for sampling the individual speedFactor of each vehicle by giving one of the following attributes in the element:

The default for passenger cars is "normc(1, 0.1, 0.2, 2)" which implies that ~95% of the vehicles drive between 80% and 120% of the legal speed limit.

Instead of giving the multi-parameter definition above, a simpler definition style is also possible.

When using the attributes in this way, the default cut-off range [0.2, 2] remains unchanged.

Caution

The distribution mean must fall within the cut-off range. In order to use mean values below 0.2 or above 2.0, the 4-parameter version must be used to modify the cut-off parameters as well.

Caution

Attribute speedFactor has three different meanings: in a it defines the individual speedFactor directly. In a if given as a single floating point value, it defines the mean of the speed distribution and when giving as norm(...) / nomrc(...), it defines the whole distribution.

When defining a vehicle type with a vClass, the following default speed-deviation will be used.

Note

before version 1.0.0, the default speedDev values was 0

Instead of configuring speed distributions in a definition (as explained below), the sumo-option --default.speeddev can be used to set a global default. The option value overrides all vClass-defaults. Setting --default.speeddev 0 estores pre-1.0.0 behavior.

The center of the speed distribution is defined relative to the road speed limit. On some roads, different speed limits may apply to cars and trucks. To model this, vClass-specific speed limits may be defined either in the network or directly in an additional file:

Note, that the given type id refers to an edge type rather than a vehicle type. The edge type may be set to an arbitrary value in the network file.

Note

When used for pedestrians, the speedFactor attribute is applied directly to the maximum speed of the vType since speed limits are not applicable to pedestrians

Note

If the specified departSpeed of a vehicle exceeds the speed limit and it's vType has a speedFactor deviation > 0, the individual chosen speed multiplier is at least high enough to accommodate the stated depart speed.

Define a flow of vehicles that desire to drive at 120% of the speed limit without any deviation:

Define a vehicle type with high speed deviation and no cut-off

Due to the work on car following models, we decided to use two values for vehicle length. The length-attribute describes the length of the vehicle itself. Additionally, the minGap-attribute describes the offset to the leading vehicle when standing in a jam.

This is illustrated in the following image:

Within the simulation, each vehicle needs - when ignoring the safe gap - length+minGap. But only length of the road should be marked as being occupied.

A SUMO vehicle may be assigned to an "abstract vehicle class", defined by using the attribute vClass. These classes are used in lane definitions and allow/disallow the usage of lanes for certain vehicle types. One may think of having a road with three lanes, where the rightmost may only be used by "taxis" or "buses". The default vehicle class is passenger (denoting normal passenger cars).

Caution

Routing or insertion may fail due to a mismatch between a vehicles vClass and the road permissions. This can be diagnosed in sumo-gui by highlighting edges according to their permissions.

The following vehicle classes exist:

These values are a "best guess" of somehow meaningful values, surely worth to be discussed. Though, in parts, they represent classes found in imported formats. They are "abstract" in the means that they are just names only, one could build a .5m long bus.

Note

vClass values are mainly used for determining access restrictions for lanes and edges. Since version 0.21.0 they will also affect the defaults of some other vType parameters. These defaults are documented at Vehicle_Type_Parameter_Defaults.

The following vehicle deprecated classes exist for maintaining backward compatibility:

The emission class represents a certain emission class. It is defined using the emissionClass attribute. Possible values are given in Models/Emissions and its subsections.

For a nicer visualization of the traffic, the appearance of a vehicle type's vehicles may be changed by assigning them a certain shape using the guiShape attribute. These shapes are used when setting the drawing mode for vehicles to simple shapes. The following shapes are known:

Some of these classes are drawn as a sequence of carriages. The length of a single carriage is indicated in parentheses after the type. For these types, the length of the vehicleType is used as the overall length of the train (all carriages combined). For example, a vehicle with shape rail/cargo and length 70m will have 5 carriages. The number of carriages will always be a whole number and no carriage will be shorter than the length given in brackets but may be longer to meet the length requirements of the whole vehicle. When drawing vehicles with raster images, the image will be repeated for each carriage.

In addition, one can determine the width of the vehicle using the attribute width. When using shapes, one should consider that different vehicle classes (passenger vehicles or buses) have different lengths. Passenger vehicles with more than 10m length look quite odd, buses with 2m length, too.

Caution

Not all of these named shapes have a distinct visualization.

Further parameters can be used to achieve visualization of individual rail carriages

The car-following models currently implemented in SUMO are given in the following table.

Caution: currently under work

Caution: Default parameters result in very conservative lane changing gap acceptance

Caution: lacking documentation

Caution: lacking documentation

Caution: lacking documentation

Mostly, each model uses its own set of parameters. The following table lists which parameter are used by which model(s). Details on car-following models and their parameters can be found here.

To select a car following model the following syntax should be used:

The default model is a modification of the model defined by Stefan Krauß in Microscopic Modeling of Traffic Flow: Investigation of Collision Free Vehicle Dynamics. The implemented model follows the same idea as that of Krauß, namely: Let vehicles drive as fast as possibly while maintaining perfect safety (always being able to avoid a collision if the leader starts braking within leader and follower maximum acceleration bounds). The implemented model as in /src/microsim/cfmodels/MSCFModel_Krauss.cpp has the following differences:

The lane-changing models currently implemented in SUMO are given in the following table.

Caution: This model may technically be used without activating sublane-simulation but this usage has not been fully tested and may not work as expected.

Mostly, each model uses its own set of parameters. The following table lists which parameter are used by which model(s).

The parameters are set within the :

Note

parameter 'lcMaxSpeedLatStanding' will not be applied when a vehicle is at the end of its lane (to ensure that there are no deadlocks).

Caution

Modifying and Retrieving lane change model attributes via TraCI works different from other vType attributes

The behavior at intersections may be configured with the parameters listed below.

The parameters are set within the :

The impatience of a driver is value between 0 and 1 that grows whenever the driver has to stop unintentionally (i.e. due to a jam or waiting at an intersection). The impatience value is computed as

Where baseImpatience is configured by setting the vType-attribute impatience and timeToMaxImpatience is set using the option --time-to-impatience (default 300s). Setting this option to 0 disables impatience growth. The value of baseImpatience may be negative to slow the growth of the dynamically computed impatience. It may also be defined with the value off to prevent drivers from becoming impatient.

The impatience value is used to represent a drivers willingness to impede vehicles with higher priority. At a value of 1 or above, the driver will use any gap that is safe in the sense of collision-avoidance even if it means that another vehicle has to brake as hard as it can. At a value of 0, the driver will only perform maneuvers that do not force other vehicles to slow down. Intermediate values interpolate smoothly between these extremes.

Junction model parameters that are expected to change during the simulation are modelled via generic parameters. The following parameters are supported (via xml input and traci.vehicle.setParameter):

If multiple ignore parameters are set, they are combined with "or". Foes are ignored while they are approaching a junction and also while they are on the junction.

Example:

If the type attribute of a vehicle is not defined it defaults to "DEFAULT_VEHTYPE". By defining a vehicle type with this id () the default parameters for vehicles without an explicitly defined type can be changed. The change of the default vehicle type needs to occur before any reference to the type was made, so basically before any vehicle or vehicle type was defined. So it should always be at the top of the very first route file.

Instead of defining routes and vTypes explicitly for a vehicle sumo can choose them at runtime from a given distribution. In order to use this feature just define distributions as following:

Note

The python tool createVehTypeDistributions.py can be used to generate large distributions that vary multiple vType parameters independently of each other.

Multiple distributions can make use of the same types and optionally override their probabilites

A distribution has only an id as (mandatory) attribute and needs a probability attribute for each of its child elements. The sum of the probability values needs not to be 1, they are scaled accordingly. Note, that probability defaults to 1.00 when not specified. At the moment the id for the children is mandatory, this is likely to change in future versions.

A distribution can be used just as using individual types and routes:

Caution

When using duarouter with input files containing distributions, the output files will contain a fixed route and type for each vehicle and the distributions will be gone. This is to ensure that the each vehicles route will fit its sampled vClass when using the input files with sumo

Vehicles may be forced to stop for a defined time span or wait for persons by using the stop element either as part of a route or a vehicle definition. The stop element can also be used to guide vehicles along a route to a waypoint. The examples below show all three cases:

The resulting vehicle v0 will stop twice, once at lane middle_0 because of the stop defined in its route and the second time because of the stop defined in the vehicle itself. The first stop will last 20 seconds the second one until simulation second 50. For a detailed list of attributes to stops see below. For a description on how to use them to simulate public transport see Simulation/Public Transport. The second vehicle v1 will stop once at lane middle_0 as defined in the route, then head to lane end_1 and pass that point at 13.89 m/s before terminating at route at rend edge.

Stops can be childs of vehicles, routes, persons or containers.

Caution

If triggered is true then parking will also be set to true by default. If you then set parking to false you may create deadlocks which prevent the simulation from terminating

Note

Bus stops must have a length of at least 10

By defining attribute 'speed' with a positive value, the stop definition is turned into a waypoint. The vehicle will drive past the given lane and keep the defined speed while between startPos end endPos.

Special handling of other attributes:

When defining attribute 'jump' with a non-negative value, the vehicle will leave the network for the given duration and re-enter it on the edge of it's next stop (or on it's arrival edge). Any intervening edges are skipped and it is permitted to have a disconnected route between the start and end of the jump.

A typical use case for jumps would be a public transport vehicle that has some of it's stops outside the simulated area and is expected to re-enter it at a later time after leaving the simulation (while preserving it's ID and delay).

Caution

The next stop must be on a different edge that that on which the jump started or the next stop will be skipped.

A color is defined as red,green,blue or red,green,blue,alpha either in a vehicle, route or vType.

In the default visualization settings the vehicle color will be used if define, otherwise the type and finally the route color. These settings can be changed.

By default color components should be given as integers in the range of (0,255) but other definitions are also supported:

The transparency value (alpha) only takes effect when also using the vType attribute imgFile.

Vehicle devices are used to model and configure different aspects such as output (device.fcd) or behavior (device.rerouting).

The following device names are supported and can be used for the placeholder below

Some devices are assigned automatically. Every that is loaded into the simulation is automatically equipped with a rerouting device to perform the initial route computation.

Other devices such as fcd are assigned automatically when the option --fcd-output is set.

Devices can be configured globally for all vehicles in the simulation by setting the option --device..probability (e.g. --device.fcd.probability 0.25. This will equip about a quarter of the vehicles with an fcd device (each vehicle determines this randomly with 25% probability).) To make the assignment exact the additional option --device..deterministic can be set Another option is to pass the list of vehicle ids that shall be equipped using the option --device..explicit .

Note

These options take precedence over automatic assignment by output-option.

Another option for assigning devices for vehicle types or individual vehicles is by using generic parameters. This is done by defining them for the vehicle or the vehicle type in the following way:

Note

The of a vehicle has precedence over the of the vehicle's type. Both have precedence over the assignment by options.